---
title: Invoke job by client id, positional values (canonical flow)
summary: Gates a caller-supplied job against the uc4.rules allow/deny list and forwards it, with positional values named arg1, arg2, and so on, to the downstream UC4 scheduling service.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-22
operation_id: OP-006
trigger: A SOAP caller invokes ExecuteJobWithValuesAndClientId on the UC4 route
---

# OP-006: Invoke job by client id, positional values (canonical flow)

This process backs the `ExecuteJobWithValuesAndClientId` operation. It is the **canonical flow** for this host; the other seven operations are documented as deltas against it on their own pages. **Transaction boundary: none** — the host opens no unit of work, no transaction, and no compensating path; the forward call to the downstream service is the only side effect and it is not undone if anything after it fails.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-006 |
| **Trigger** | SOAP caller invokes `ExecuteJobWithValuesAndClientId` |
| **Entry operation** | [`ExecuteJobWithValuesAndClientId`](../contracts/uc4-service.md#executejobwithvaluesandclientid) |
| **Owning component** | `UC4Service.ExecuteJobWithValuesAndClientId` |
| **Inputs** | `environment` (`short`), `jobName` (`string`), `values` (`params string[]`) |
| **Outputs** | `UC4Result` — the mapped downstream result, or an empty result if the job is blocked |
| **Failure behavior** | An unhandled exception is surfaced by the WCF framework as a generic SOAP fault carrying full exception detail |

## Request and response

| Direction | Element | Type | Declared in | Notes |
| --- | --- | --- | --- | --- |
| Request | `environment` | `short` | `src/WCF/SAIF.Services.WCF.UC4.Host/UC4Service.cs:186` | Client id identifying the environment |
| Request | `jobName` | `string` | `UC4Service.cs:186` | The job to invoke |
| Request | `values` | `params string[]` | `UC4Service.cs:186` | Positional parameters; empty array if omitted |
| Response | `<return>` | `UC4Result`* | `UC4Service.cs:186` | Mapped downstream result, or an empty `UC4Result` if blocked |

## Steps

1. WCF dispatcher activates `UC4Service` through the parameterless constructor, which builds `WcfEnvironmentService(OperationContext.Current.RequestContext)` and `LogService(envSvc)` (`UC4Service.cs:31, 38`).
   - On failure: activation failure surfaces as a WCF default fault.
2. `UC4Service.Logging` sets the trace threshold to `INFO` and emits `method:{method},jobName:{jobName}` (`UC4Service.cs:187, 259-262`) — [BR-UC4-008](../business-rules.md#br-uc4-008-every-invocation-is-traced-at-info).
   - On failure: a logging exception propagates as a WCF default fault.
3. `Enforce.ArgumentNotNull` rejects a null `jobName` (`UC4Service.cs:189`) — [BR-UC4-004](../business-rules.md#br-uc4-004-job-name-must-not-be-null).

   > **Origin**: Step 3 is implemented in `Enforce.ArgumentNotNull` in `SAIF.Services.Utilities` (`SAIF.Framework.Core`, external, not documented by this run) and executed within this operation.*
   - On failure: throws; caller receives a WCF default fault with exception detail.
4. `UC4Service.IsJobAllowed` reads `uc4.rules` from the environment service and deserializes it to `UC4JobRules` (`UC4Service.cs:55-56`) — [BR-UC4-001](../business-rules.md#br-uc4-001-job-allowed-by-uc4-rules-document).
   - On failure: a missing or malformed document throws at an unguarded dereference of `rules.UC4Rules.Environments` (line 61) → WCF default fault.*
5. `IsJobAllowed` selects the rule set whose `ClientId` equals `environment` (`UC4Service.cs:61`) — [BR-UC4-001](../business-rules.md#br-uc4-001-job-allowed-by-uc4-rules-document).
   - Sub-step (no matching rule set): allow unless `environment == 100` (`UC4Service.cs:64-77`) — [BR-UC4-002](../business-rules.md#br-uc4-002-default-allow-for-unmatched-environment). No fault; the decision and its (discarded) explanatory message are computed.
   - Sub-step (rule set found): take `AllowByDefault.ToBoolean()` as the baseline, then scan `Rules` in order; the first case-insensitive regex or literal match on `jobName` flips the baseline and breaks (`UC4Service.cs:80-106`) — [BR-UC4-003](../business-rules.md#br-uc4-003-rule-evaluation-order-and-match-type). An invalid regex in the rule document throws → WCF default fault.*
6. `IsJobAllowed` composes the explanatory `message` for the decision (`UC4Service.cs:108-128`).
7. If not allowed: `UC4Service` returns `new UC4Result()` and **discards `message`** (`UC4Service.cs:191-194`) — [BR-UC4-005](../business-rules.md#br-uc4-005-blocked-job-returns-empty-result-with-no-explanation). This is not a fault — the caller receives an empty result with no reason.
   - Otherwise: continue to step 8.
8. `UC4Service.GetParameters` converts the positional `values` to `arg1`, `arg2`, and subsequent key/value pairs (`UC4Service.cs:195, 227-235`) — [BR-UC4-009](../business-rules.md#br-uc4-009-positional-values-are-named-arg1-arg2).
9. The `UC4Client` constructor resolves `uc4coreapi.url` and `uc4coreapi.schedulejobroute` from the environment service, builds `ClientInfo` from the **host's** `MachineName`/`UserName` and `ApplicationId = "wcf_uc4"`, and constructs the packaged `Proxy` (`Uc4Client.cs:24-33`) — [BR-UC4-010](../business-rules.md#br-uc4-010-downstream-service-address-resolved-per-call), [BR-UC4-011](../business-rules.md#br-uc4-011-forwarded-job-stamped-with-host-identity).

   > **Origin**: Step 9's downstream client construction is implemented in `SAIF.Web.API.Clients` / `SAIF.Services.UC4` (external packages, not documented by this run) and executed within this operation.*
   - On failure: a missing setting or unreachable address throws → WCF default fault.
10. `UC4Client.ScheduleJob` projects the pairs to a dictionary and calls the downstream `IUC4Service.ExecuteJob(jobname, parameters)` (`Uc4Client.cs:50-54`).
    - On failure: a downstream exception propagates unchanged → WCF default fault with exception detail.
11. `UC4Client.ConvertFromClientToCoreContractForUC4Results` maps the downstream `SAIF.Services.UC4.UC4Result` field-by-field onto `SAIF.Core.Contracts.UC4.UC4Result` (`Uc4Client.cs:55-74`) — [BR-UC4-012](../business-rules.md#br-uc4-012-downstream-result-mapped-field-by-field).
    - On failure: a `NullReferenceException` is possible if the downstream result is null.*
12. WCF dispatcher serializes the `UC4Result` onto the default `basicHttpBinding` endpoint.

## Process flow

```mermaid
flowchart TD
    A["Activate UC4Service"] --> B["Log invocation<br>at INFO"]
    B --> C["Enforce jobName<br>not null"]
    C -->|"null"| CFAULT["Detailed WCF fault"]
    C -->|"ok"| D["Read uc4.rules,<br>select rule set"]
    D -->|"read/parse fails"| DFAULT["Detailed WCF fault"]
    D --> E{"Rule set found?"}
    E -->|"No"| F["Allow unless<br>environment == 100"]
    E -->|"Yes"| G["AllowByDefault baseline,<br>first match flips it"]
    G -->|"invalid regex"| GFAULT["Detailed WCF fault"]
    F --> H{"Allowed?"}
    G --> H
    H -->|"No"| I["Return empty UC4Result<br>message discarded"]
    H -->|"Yes"| J["Name positional values<br>as arg1, arg2, in order"]
    J --> K["Resolve downstream address,<br>stamp host identity"]
    K -->|"missing setting"| KFAULT["Detailed WCF fault"]
    K --> L["Forward job to<br>downstream service"]
    L -->|"downstream throws"| LFAULT["Detailed WCF fault"]
    L --> M["Map downstream result<br>to published UC4Result"]
    M -->|"null result"| MFAULT["Detailed WCF fault"]
    M --> N["Serialize and return"]
    I --> N
```

## Transaction and side effects

| Aspect | Finding |
| --- | --- |
| Unit of work | None |
| Commit point | Not applicable — no persistence |
| Records written | None locally — downstream persistence, if any, is out of scope |
| Downstream calls | `UC4Client.ScheduleJob` → downstream UC4 scheduling service |
| Shared state touched | None |
| Repeat-call behavior | Not idempotent from the host's perspective — each call forwards a new job-execution request to the downstream scheduler |

## Faults and error handling

| Failure | Fault type the caller receives | Produced by | Source |
| --- | --- | --- | --- |
| `jobName` null | Generic SOAP fault, full exception detail | The WCF framework — no `IErrorHandler` is confirmed for this class | `UC4Service.cs:189` |
| `uc4.rules` missing/malformed | Generic SOAP fault, full exception detail | The WCF framework | `UC4Service.cs:61` |
| Invalid rule regex | Generic SOAP fault, full exception detail | The WCF framework | `UC4Service.cs:80-106` |
| Downstream construction/call failure | Generic SOAP fault, full exception detail | The WCF framework | `Uc4Client.cs:24-54` |

`UC4Service` carries `[LogErrorBehavior]`, an external `IServiceBehavior` whose implementation is not in this repository; by the shape of its in-repository sibling, its contribution is observability, not fault shaping — see [Faults and error pipeline](../faults.md).

## Authorization

| Requirement | Enforced by | Source | Applies to |
| --- | --- | --- | --- |
| [None in code](../authentication-authorization.md#access-requirements-per-operation) | Nothing — no attribute or programmatic check exists | `UC4Service.cs:186` | This operation |

## Related documentation
- [Index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Activation and hosting](../activation-hosting.md)
- [Operations](../operations.md)
- [Faults and error pipeline](../faults.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources
- `src/WCF/SAIF.Services.WCF.UC4.Host/UC4Service.cs`
- `src/WCF/SAIF.Services.WCF.UC4.Host/Uc4Client.cs`
- `src/WCF/SAIF.Services.WCF.UC4.Host/UC4JobRules.cs`